home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 9 / Night Owl CD-ROM (NOPV9) (Night Owl Publisher) (1993).ISO / 050a / _tsgrep.zip / TSGREP.DOC < prev    next >
Text File  |  1993-05-04  |  23KB  |  567 lines
  1. /****************************************************************************
  2.              TSGREP ... A regular expression line extractor
  3.                               David Marcus
  4. ****************************************************************************
  5.                               Version 4.6
  6.                              **************
  7.  
  8. Copyright: 1993 David Marcus
  9.  
  10.         Permission is granted to all persons for non-commercial
  11.         distribution of this file and the macros and ideas contained
  12.         herein provided (a) credit is given to the author and (b) all
  13.         changes not made by the author are attributed.
  14.  
  15.         Permission is granted to SemWare for commercial distribution
  16.         provided (a) and (b) above.
  17.  
  18. Author:  David Marcus
  19.  
  20. Date:    4-27-93
  21.  
  22. Description:
  23.  
  24.         TSGREP is a line extractor that searches groups of files
  25.         and lists line matching a search string.
  26.  
  27. Installation:
  28.  
  29. 1. Place TSGREP.S in the directory where your macro source files reside.
  30.  
  31. 2. (optional; required for command line operation only) Place TSGREP.BAT
  32.    in a directory on your path. If your copy of TSE is not named e.exe,
  33.    edit TSGREP.BAT to change the name from e to whatever you use.
  34.  
  35. 3. Advanced Users: In TSGREP.S, the string ':U:' appears on each line
  36.    that contains the initial setting of a toggle or mode. Search for :U:
  37.    and customize as you like.
  38.  
  39. 4. Compile TSGREP using sc:
  40.  
  41.      sc TSGREP
  42.  
  43.  
  44. Usage Notes:
  45.  
  46. ■ Contents:
  47.      Quick Start
  48.      Current option summary
  49.      Current special character summary
  50.      Enhancements since first version, backwards by date.
  51.      How to use TSGREP. (May not include all enhancements.)
  52.      TSGREP.BAT
  53.  
  54. ■ Quick Start
  55.  
  56.      Type TSGREP at the command line.
  57.  
  58.      You give TSGREP:
  59.  
  60.           * a search string
  61.           * filespec(s) to search
  62.           * search options
  63.           * the name of a temp file to create
  64.  
  65.      TSGREP gives you:
  66.  
  67.           * A file that includes each line with the search string on it
  68.           * The ability to press ctrl+enter to go to load the file and
  69.             go to line listed at the current cursor position. You can
  70.             then press ctrl+enter to go back to the list file.
  71.           * Help when you press alt+h.
  72.  
  73.  
  74.      Bells & Whistles:
  75.  
  76.           * TSGREP shows on-screen help for each prompt.
  77.           * You can run TSGREP from the command line, specifying all
  78.             arguments on the command line. Type TSGREP /H for syntax
  79.             help.
  80.           * You can specify searching of files in subdirectories of the
  81.             one that is part of the search filespec.
  82.           * If you enter multiple filespecs, and one or more don't have
  83.             a drive or path, TSGREP uses the drive and path with the
  84.             prevous spec. For instance, if you say to search
  85.             "i:\usr\both\*.asc" and also "*.doc", TSGREP searches
  86.             "i:\usr\both\*.asc" and also "i:\usr\both\*.doc".
  87.           * You can specify files to never search as within TSGREP'
  88.             source code or as part of the batch file. (TSGREP is preset
  89.             to ignore  .img .exe .com .dll .tif .pcx .$hp .$sc .cif &
  90.             .vgr in its source code, and  .bak & .$hp in the batch file.
  91.           * You can use "-or-" or "-and" in your search string without
  92.             using regular expression syntax.
  93.           * TSGREP automatically searches any loaded files, but never
  94.             leaves more files loaded than you started with.
  95.           * You can run TSGREP from the DOS prompt using the batch file
  96.             TSGREP.BAT to skip all prompts. TSGREP.BAT is contained at the
  97.             end of this file.
  98.           * TSGREP processes "list files" - files containing a list of
  99.             files or file specs to process.
  100.           * When you are looking at the list file TSGREP produces, you
  101.             can toggle to seeing only file names or file names + hits.
  102.             You can remove a file and its entries from the list ... and
  103.             later restore all removed files - they are again part of the
  104.             list. You can use alt+p and alt+n to directly to the previous
  105.             or next file in the listing. And you can use alt+h for help.
  106.  
  107. ■ Current option summary (in addition to SE std options):
  108.  
  109.      \#   - don't include line numbers
  110.      \_   - don't convert underscores in search string to spaces
  111.      \l   - [lower case "el"] don't load outfile
  112.      \1   - [numeral "one"] don't find more than 1 hit per file
  113.      \w   - don't write copy of  lines with hits to outfile;
  114.                only list file names
  115.      \x   - don't kick in regular expression search automatically
  116.  
  117.      The following SE find options are either always ignored or always
  118.      used by TSGREP; do not use them: b, g, l, +.
  119.  
  120. ■ Current special character summary:
  121.  
  122.      Search string:
  123.           -or-  means | ("or")
  124.           -and- means "and"
  125.           _     means " "
  126.           \-    means "="
  127.           [[    means "<"
  128.           ]]    means ">"
  129.  
  130.      Input file spec:
  131.           + (at end)     - recursive directory searching
  132.           ^              - connects two separate file specs
  133.           @              - part of list file name
  134.  
  135. All special characters in searchstring and in options are user-configurable.
  136.  
  137. ■ Current keystroke summary:
  138.  
  139. Keystrokes while in file listing hits:
  140.      <alt F>   Toggle showing lines with hits or only filenames
  141.      <alt N>   Goto next file in listing
  142.      <alt P>   Goto prev file in listing
  143.      <alt R>   Remove the entries for a file
  144.      <alt U>   Undo all removes
  145.      <alt enter>    Edit file/line cursor is on
  146.      <alt esc> Save outfile and exit
  147.      <alt h>   Help
  148.      <alt ->   Unload TSGREP
  149.  
  150. Keystrokes while editing one of the files listed:
  151.      <alt N>   Goto next hit in file
  152.      <alt P>   Goto prev hit in file
  153.      <alt escape> Exit
  154.      <alt enter>  Go back to the file listing hits
  155.      <alt h>   Help
  156.      <alt ->   Unload TSGREP
  157.  
  158. ────────────────────────────────────────────────────
  159. ■  5-4-93 When interactively run and query saves is set to TRUE,
  160.           TSGREP now checks each file and, if changed, queries whether
  161.           to save changes or not. If not files are changed, no query is
  162.           performed.
  163.  
  164. ■ 12-22-92 Fixed bug where loaded files were not being saved when the
  165.           query_saves flag was set to NO.
  166.  
  167.           TSGREP will prompt for all arguments, and show help for each,
  168.           when started like this:
  169.  
  170.           C:> e -eTSGREP
  171.  
  172.           TSGREP.BAT now allows for this; just type TSGREP to start it
  173.           this way. (I recommend you replace your SGRP.BAT with the one
  174.           in this ZIP file.)
  175.  
  176.           The files-only buffer is now saved as the filename defined as
  177.           default_name_2. This is not particularly desireable, but
  178.           necessary. Note that the unload function will delete this file
  179.           from disk.
  180.  
  181.           Changed help for keystrokes so that (a) it pops up whenever
  182.           <alt h> is hit and (b) it does not pop up automatically when
  183.           TSGREP is done.
  184.  
  185.           Added <alt -> to unload TSGREP. All buffers used by TSGREP are
  186.           freed except the one containing the output file. Keys revert
  187.           to pre-TSGREP assignments.
  188.  
  189.           Added an integer for the normal attribute and the hilite
  190.           attribute to be used by TSGREP. These are defined as
  191.  
  192.      normal_attr = Query(TextAttr)      // attribute for normal text
  193.      normal_attr = Query(HiLiteAttr)    // attribute for highlighting
  194.  
  195.           If you have TSE configured to use the same attributes for
  196.           these two items, change one of these items. Also do this if
  197.           you ahve one of them set to blink!
  198.  
  199.           NOTE: These are found at the beginning of Main().
  200.  
  201. ■ 12-21-92 For Tom Hogshead: The characters written before and after
  202.           each file name are now configurable:
  203.  
  204.      name_prefix[4] = '  ',     // inserted into outfile before name
  205.      name_suffix[4] = ': ',        // inserted into outfile after name
  206.      name_prefix_re[8] = ''        // version of above with and regexp
  207.                                    // characters escaped out (created by
  208.                                    // TSGREP)
  209.  
  210.           Note that name_prefix_re must be double the length
  211.           of name_prefix.
  212.  
  213. ■ 12-20-92 For Tom Hogshead: TSGREP now operates while in an edit
  214.           session. Help is provided for each input option. As a result,
  215.           TSGREP is now approximately 11k. (To reduce the size of TSGREP,
  216.           edit ask_input() to remove the help text.)
  217.  
  218.           Files currently in the ring are always searched. Files added for
  219.           filespec prompt are searched additionally.
  220.  
  221.           Files in the ring are unloaded after being searched (to prevent
  222.           any VM slows). Each is saved to disk first. If you set the
  223.           integer query_flags to TRUE, the save will be queried; if you
  224.           don't save, TSGREP aborts.
  225.  
  226.           Files in the ring are reloaded after TSGREP finishes. Current
  227.           row is restored for each.
  228.  
  229.           Note: If the environment variable SSTRING is set (to
  230.                 anything), TSGREP assumes that you do NOT want to be
  231.                 prompted for the arguments, and executes using
  232.                 environment variables (without prompting). So, be sure
  233.                 that your batch file resets SSTRING to '' after
  234.                 execution.
  235.  
  236.           You can start TSGREP in batch. Then, with the outfile loaded
  237.           (or any other), you can restart it (via execmacro) and it will
  238.           prompt you for values.
  239. ■ 12-18-92 No longer uses List() to display files.
  240.  
  241.           Keystrokes and specific functions added; see above,
  242.  
  243.           Added ++ to mean "AND" in the search string. May be only used
  244.           once in the string. Order is not important; a++b means (a.*b or
  245.           b.*a) ... and that is exactly how it is implemented.
  246.  
  247.          If combining OR with AND, use braces to surround the terms
  248.          being ORd; results will be unpredictable otherwise. For instance
  249.          if you use this:
  250.               sort++{search-or-subtotal}
  251.          TSGREP will it interpret it as:
  252.               {{sort.*{search}|{subtotal}} | {{search}|{subtotal}.*sort}}
  253.          (spaces added for clarity)
  254.  
  255. ■ 12-14-92 Made a change to speed recursive directory searching slightly.
  256.          However, TSGREP now does not search directories that have
  257.          extensions as part of the file name (created by a command such
  258.          as "MKDIR C:\SE.62"). If you have directories such as that and
  259.          you wish them search, change the line
  260.                dir_spec = '*.',
  261.           to
  262.                dir_spec = '',
  263.           This is in the global string definitions section.
  264.  
  265. ■ 12-11-92 Added header for files with finds.
  266.          Added option (\w) to suppress the writing of lines with hits
  267.          in the output file. When this is used, TSGREP prepares a list of
  268.          files with hits but does not include the text of the hit.
  269.          Gotohit will still got to the first hit, however.
  270.  
  271.          All special character in searchstring and in options are now
  272.          user configurable.
  273.  
  274. ■ 12-9-92 <Escape> to abort added during processing. <escape> is checked
  275.         before each file load and before each recursive directory check.
  276.  
  277.         Options are now the 3rd argument in the TSGREP batch file, and
  278.         outfile is 4th. This means that options can be used without
  279.         outfile, but must be used if outfile is to be specified.
  280.  
  281.         The output file is now loaded for editing _unless_ \l
  282.         is used as an option. (The e option is no longer used.)
  283.  
  284.         If the search string includes any of the strings listed below
  285.         then regular expression search is set unless \x is used as an
  286.         option:
  287.                -or-
  288.                -OR-
  289.                .*
  290.                [
  291.                ++
  292.  
  293.         See the definition for EXCLUDE for a set of extensions now hard-
  294.         coded in TSGREP as extensions to be ignored.
  295.  
  296.         In multiple filespec processing, if a filespec has no drive and
  297.         path, the ones for the preceding filespec are applied to it.
  298.         For instance:
  299.           TSGREP searchstring i:\usr\*.txt^*.doc^c:\*.txt^*.doc
  300.         is processed as
  301.           TSGREP searchstring i:\usr\*.txt^i:\usr\*.doc^c:\*.txt^c:\*.doc
  302.  
  303. ■ 12-5-92 Recent changes include recursive searching of subdirectories,
  304.         initiated by adding a "+" to the end of any filespec or entry in a
  305.         listfile.
  306.  
  307.         When '-or-' or '-OR-' is used in a regular expression search,
  308.         braces are added automatically. For instance:
  309.           TSGREP sort-or-search
  310.         is processed as
  311.           TSGREP {sort}|{search}
  312.  
  313.         Use \1 as a search option to stop searching each file after
  314.         1 hit found.
  315.  
  316.        TSGREP now attempts to not load any file whose extension matches a
  317.        list in an environment variable (and never searches these files).
  318.  
  319. /───────────────────────────────────────────────────────────────────────
  320.  
  321. ■ How to Use TSGREP
  322. ──────────────────
  323.  
  324. 1. While in an edit session:
  325.  
  326.    Just load and execute like any other macro.
  327.    You'll be prompted for the information TSGREP needs.
  328.  
  329.    Note that if the environment variable SSTRING is set (to anything),
  330.    TSGREP assumes that you do NOT want to be prompted for the arguments,
  331.    and executes using values from the DOS environment. So, be sure that
  332.    your batch file resets SSTRING to '' after execution.
  333.  
  334. 2. Use TSGREP in a batch file, named (I hope) TSGREP.bat, as follows:
  335.  
  336.    C:> TSGREP searchstring filespec [options [outfile]]
  337.  
  338. 3. Using TSGREP in a batch file, named (I do hope) TSGREP.BAT, as follows:
  339.  
  340.    D:> TSGREP
  341.  
  342.    Executing TSGREP from the DOS command line:
  343.  
  344.    D:> E -eTSGREP <enter>
  345.  
  346.    In either case, TSGREP prompts for all arguments, showing help for each
  347.    as it prompts.
  348.  
  349. You can start TSGREP with the batch file. Then, with the outfile loaded
  350. (or any other), you can restart it (via execmacro) and it will prompt
  351. for values. I myself have it tied to <alt s><g>:
  352.  
  353.   <alt S> <g>         Execmacro('sgrep')
  354.  
  355. ■ Search String
  356. ───────────────
  357. Your search string may be any QEdit search string.
  358. However:
  359.  
  360.   * Use -or- instead of | to avoid DOS piping. -OR- is ok, too. [1]
  361.  
  362.   * If -or- is NOT surrounded by }{, TSGREP will supply the braces. So,
  363.             menu-or-proc-or-keydef
  364.        gets turned into
  365.             {menu}|{proc}|{keydef}
  366.     All braces you supply will be honored, too.
  367.  
  368.   * Use _ instead of space. [1]
  369.     (Use \_ in options to force reading of _ as an underscore)
  370.  
  371.   * Use \- for = [1]
  372.  
  373.   * Use ++ to mean "AND" in the search string. May be only used
  374.     once in the string. Order is not important; a++b means (a.*b or
  375.     b.*a) ... and that is exactly how it is implemented.
  376.  
  377.     If combining OR with AND, use braces to surround the terms
  378.     being ORd; results will be unpredictable otherwise. For instance
  379.     if you use this:
  380.           sort++{search-or-subtotal}
  381.      TSGREP will it interpret it as:
  382.           {{sort.*{search}|{subtotal}} | {{search}|{subtotal}.*sort}}
  383.      (spaces added for clarity)
  384.  
  385.   * Use [[ to mean < in the search string. [1]
  386.     Use ]] to mean > in the search string. [1]
  387.  
  388. NOTE: [1] Required when entering the search string from the DOS command
  389.           line.
  390.  
  391. ■ Input File Spec
  392. ─────────────────
  393. Infile may be any valid filespec, wildcards included.
  394.  
  395. When TSGREP operates during an edit session, files currently in the ring are always
  396. searched. Files specified at the filespec prompt are searched
  397. additionally; the original ring is restored after the searches, and no
  398. additional files are left loaded.
  399.  
  400. Use ^ as a separator for multiple files, as in:
  401.      TSGREP sort *.q^*.inc^q:c*.??c
  402.  
  403. In multiple filespec processing, if a filespec has no drive and
  404. path, the ones for the preceding filespec are applied to it.
  405. For instance:
  406.      TSGREP searchstring i:\usr\*.txt^*.doc^c:\*.txt^*.doc
  407. is processed as
  408.      TSGREP searchstring i:\usr\*.txt^i:\usr\*.doc^c:\*.txt^c:\*.doc
  409.  
  410. Files with '@' in any position of the name are treated as list files.
  411. List files may contain:
  412.      * specific file names
  413.      * wildcarded filespecs
  414.      * additional listfile names
  415. Place one spec per line, starting each in column 1.
  416.  
  417. You can use multiple list files on the command line or combine them
  418. with other filespecs.
  419.  
  420. Add a plus sign to the end of a filespec to have TSGREP process
  421. matching files in subdirectories of the specified one. You can use
  422. the plus sign both in filespecs and inside listfiles. TSGREP builds its
  423. list of subdirectories once for each plus sign you use, so it may be more
  424. efficient to use other strategies than this.
  425.  
  426. Also, if you use this feature, be *sure* to set the variable RAMDRIVE.
  427.  
  428. As a by-product, the command
  429.      tsgrep .* c:\nul+ \w
  430. generates a list of all directories on your disk.
  431.  
  432. TSGREP ignores any files whose extension is found in the list specified by
  433. the environment variable EXCLUDE or the definition of the string
  434. EXCLUDE.
  435.  
  436. NOTES: 1. You cannot use the ^ separator inside a list file.
  437.        2. List files must actually have the @ as part of the file name.
  438.        3. TSGREP now not search directories that have extensions as part
  439.           of the file name (created by a command such as "MKDIR C:\SE.62").
  440.           If you have directories such as that and you wish them searched,
  441.           change the line
  442.                dir_spec = '*.',
  443.           to
  444.                dir_spec = '',
  445.           This is in the global string definitions section.
  446.  
  447. ■ Search Options
  448. ────────────────
  449. Options may be any QEdit search options except 'b', 'g' and '+'. (These
  450. are used automatically, as appropriate, and are screened out of options
  451. you enter.)
  452.  
  453. Default options are 'i'. If any of these strings are contained in the
  454. search string, 'x' is automatically added to the options unless '\x'
  455. is used as an option:
  456.      -or-
  457.      .*
  458.      [
  459.      ++
  460.  
  461. Use \# in options to suppress line numbers.
  462.  
  463. Use \1 to stop searching each file after 1 hit found [that's the numeral
  464.           "one"].
  465.  
  466. Use \_ to force reading of '_' in the search string as underscores
  467.           rather than spaces.
  468.  
  469. Use \l to suppress loading of t load outfile [that's a lowercase "el"].
  470.  
  471. Use \w to not write lines with hits to outfile; only list file names
  472.  
  473. Use \x  to overide automatic kick in of regular expression.
  474.  
  475. ■ Outfile
  476. ──────────
  477.  
  478. Outfile is optional; default is TSGREP.TMP or as set by the
  479. default_name string.
  480.  
  481. Files with no hits are listed at the end of outfile.
  482.  
  483. ■ Usage Notes
  484. ─────────────
  485.  
  486. Keystrokes while in the file listing hits:
  487.      <alt F>   Toggle showing lines with hits or only filenames
  488.      <alt N>   Goto next file in listing
  489.      <alt P>   Goto prev file in listing
  490.      <alt R>   Remove the entries for a file
  491.      <alt U>   Undo all removes
  492.      <alt enter>    Edit file/line cursor is on
  493.      <alt esc> Save outfile and exit
  494.  
  495. Keystrokes while editing one of the files listed:
  496.      <alt N>   Goto next hit in file
  497.      <alt P>   Goto prev hit in file
  498.      <alt escape> Exit
  499.      <alt enter>  Go back to the file listing hits
  500.  
  501. To have files searched in alpha order [OR any particular order],
  502. use an @listfile with the files in the desired order.
  503.  
  504. Use <Escape> to abort during processing. <escape> is checked before each
  505. file load and before each recursive directory check. Give it a few
  506. seconds to kick in if you use it.
  507.  
  508. When TSGREP operates during an edit session, files currently in ring are
  509. always searched. Files added for filespec prompt are searched
  510. additionally. The files in the ring are unloaded after being searched
  511. (to prevent any VM slows). Each is saved to disk first. If you set the
  512. integer query_flags to TRUE, the save will be queried; if you don't
  513. save, TSGREP aborts. Files in the ring are reloaded after TSGREP finishes.
  514. Current line is restored for each.
  515.  
  516. ■ TSGREP.BAT
  517.  
  518.      @echo off
  519.      rem Usage:
  520.      rem            TSGREP string infile [options [outfile]]
  521.      if "%1"== ""  goto :prompt_user
  522.      if "%1"== "?" goto :help
  523.      if "%2"== ""  goto :help
  524.      set string=%1
  525.      set infile=%2
  526.      set options=%3
  527.      set outfile=%4
  528.      set exclude=" .bak .$hp"
  529.      :prompt_user
  530.  
  531.      q:\e -eq:\TSGREP
  532.      goto end
  533.  
  534.      :help
  535.      echo ┌──────────────────────────────────────────────────────────────────────┐
  536.      echo │ Usage:                                                               │
  537.      echo │            TSGREP  [searchstring infile [outfile [options]]]          │
  538.      echo ╞══════════════════════════════════════════════════════════════════════╡
  539.      echo │ If no arguments given, TSGREP prompts for each one.                   │
  540.      echo │ Searchstring may be any QEdit searchstring.                          │
  541.      echo │      * Use -OR- instead of as the 'OR' indicator in expressions      │
  542.      echo │      * Use -OR- instead of as the 'OR' indicator in expressions      │
  543.      echo │      * Braces optional; default parsing supplied                     │
  544.      echo │      * Use \- instead of =                                           │
  545.      echo │      * Use _ instead of space                                        │
  546.      echo │ Infile may be any valid filespec, wildcards included.                │
  547.      echo │      Files with '@' in the name are treated as list files.           │
  548.      echo │      Add + to the end of the filesspec for recursivce search.        │
  549.      echo │      List files may be nested to 3 levels; possibly more will work.  │
  550.      echo │      Use ^ as a separator for multiple files, as in                  │
  551.      echo │           TSGREP sort *.q^*.inc^who.??q                               │
  552.      echo │ Search options may be any QEdit search options except 'b'.           │
  553.      echo │      * An additional TSGREP option is 'e', 'edit the outfile'.        │
  554.      echo │      * Default options = 'ei''                                       │
  555.      echo │      * if only 'e' entered, options set to 'ei'                      │
  556.      echo │      * Use \# in options for suppress line numbers                   │
  557.      echo │      * Use 1 in options to stop searching each file after 1 hit      │
  558.      echo │ Outfile is optional; default is TSGREP.TMP                            │
  559.      echo └──────────────────────────────────────────────────────────────────────┘
  560.      :end
  561.      set string=
  562.      set infile=
  563.      set outfile=
  564.      set options=
  565.      set exclude=
  566.  
  567. ────────────────────────────────────────────────────────────────────────── */